<html><!-- Copyright (C) 2007 Laurent A.V. Szyster - Copylef GPL 2.0 -->
<head>
  <title>protocols.js > HTTP</title>
  <link href="site.css" type="text/css" rel="stylesheet"></link>
  <link href="protocols.css" type="text/css" rel="stylesheet"></link>
</head>

<body>

<div>
  <h1 id="hourGlass"><a href="index.html">protocols.js</a></h1>
  <div class="menu">
    <a href="documentation.html">Documentation</a> &gt;
    <a href="functions.html">Functions</a>
    <a href="HTML.html">HTML</a>
    <a href="CSS.html">CSS</a>
    <a href="JSON.html">JSON</a>
  </div>
  <h2>Hypertext Transfer Protocol(HTTP)</h2>
  <ol>
    <li><a href="#HTTP.timeout">timeout</a></li>
    <li><a href="#HTTP.requests">requests</a></li>
    <li><a href="#HTTP.pending">pending</a></li>
    <li><a href="#HTTP.state">state (active)</a></li>
    <li><a href="#HTTP.urlencode">urlencode (sb, query)</a></li>
    <li><a href="#HTTP.request"
    >request (method, url, headers, body, ok, error, timeout)</a></li>
    <li><a href="#HTTP.response">response (key, ok, error)</a></li>
    <li><a href="#HTTP.abort">abort (key)</a></li>
    <li><a href="#HTTP.except">except (key, message)</a></li>
    <li><a href="#HTTP.observe">observe (state, req)</a></li>
  </ol>
  <h3>Synopsis</h3>
  <p>
    This <code>HTTP</code> client provides reliable support accross browsers 
    for asynchronous requests with timeouts and without redundant submission.
  </p>
  <p>
    ...
  </p>
  <h3><a name="HTTP.timeout" href="#">HTTP.timeout</a></h3>
  <p>
    ...
  </p>
  <h3><a name="HTTP.requests" href="#"
  >HTTP.requests</a></h3>
  <p>
    The <code>HTTP</code> client maintains a dictionnary of request 
    objects, indexed by keys made of their HTTP method and URL requested.
    This dictionnary acts as a filter to prevent redundant POST
    or GET requests to be submitted. It is usefull to inspect
    the current pending requests:
  </p>
  <pre class="synopsis" onclick="eval_synopsis(this);"
    >HTTP.request('GET', 'hello-world.js', {}, null, function (request) {
    HTML.update($('http_response'), request.responseText);
    });
for (var key in <strong>HTTP.requests</strong>) 
    if (HTTP.requests[key]!=null) 
        alert(key);</pre>
  <div id="http_response" class="test">...</div>
  <p>
    Applications may also use <code>HTTP.requests</code> test the state of 
    a pending requests by name, something practical when the state inspector 
    is independant from the request original scope and cannot possibly have 
    a reference to the <code>XmlHttpRequest</code> object.
  </p>
  <h3><a name="HTTP.pending" href="#"
  >HTTP.pending</a></h3>
  <p>
    A count of the pending requests.
  </p>
  <h3><a name="HTTP.state" href="#"
  >HTTP.state (active)</a></h3>
  <p>
    This method is called when the client starts or stop beeing active,
    whenever the number of pending requests goes from 0 to 1 or from 1 to 0.
    By default it removes or adds the <code>hidden</code> CSS class
    from the element identified as <code>hourGlass</code> in the page 
    (obviously expecting the usual animation that symbolize a busy network
    and a wait state).
  </p>
  <p>
    Applications may replace it with more elaborate hour-glasses or use
    this interface to implement network usage statistics for instance.
  </p>
  <h3><a name="HTTP.urlencode" href="#"
  >HTTP.urlencode (sb, query)</a></h3>
  <pre
    class="synopsis" 
    onclick="{HTML.update($('http_urlencode'), eval_synopsis(this));}" 
    ><strong>HTTP.urlencode(</strong>['/path'], {
    "hello": "world", "test": [1, 2, true]
    }<strong>)</strong>.join('')</pre>
  <div class="test"><code id="http_urlencode">...</code></div>
  <p>
    ...
  </p>
  <h3><a name="HTTP.request" href="#"
  >HTTP.request (method, url, headers, body, ok, error, timeout)</a></h3>
  <pre class="synopsis" onclick="eval_synopsis(this);"
    >var <strong>form</strong> = {'hello': 'world', 'test': [1, 2.0, true]};
var <strong>ok</strong> = function (request) {
    HTML.update($('http_response_post'), request.responseText);
    };
function <strong>error</strong> (status, request) {
    alert (status);
    }
var key = <strong>HTTP.request(</strong>'POST', 'hello-world.php', {
    'Content-type': 'application/x-www-form-urlencoded'
    },  HTTP.urlencode([], <strong
    >form</strong>).join(''), <strong
    >ok</strong>, <strong
    >error</strong>, 1000<strong>)</strong>;</pre>
  <pre
    >&lt;?php echo '{&quot;who&quot;: &quot;'.$_POST['hello'].'&quot;}' ?&gt;</pre>
  <div id="http_response_post" class="test">...</div>
  <p>
    <a 
    href="http://tools.ietf.org/html/rfc2616"
    >HTTP</a>
  </p>
  <h3><a name="HTTP.response" href="#"
  >HTTP.response (key, ok, error)</a></h3>
  <p>
    Application will never directly call <code>HTTP.response</code> but 
    developpers should know what it does for them. And they may want to
    substitute their own closure factory if needs be.
  </p>
  <p>
    This one returns an <code>onReadyStateChange</code> function that resolves the
    handled request by its key, calls <code>HTTP.<a 
    href="#HTTP.observe"
    >observe</a>(key, req)</code> on state 2, 3 and 4, 
    dispatch completion states between two the <code>ok(text)</code> and 
    <code>error(code, text)</code> functions, eventually catching and thunking 
    to <code>HTTP.<a 
    href="#HTTP.except"
    >except</a></code> any exceptions throwed by the dispatched response 
    handler.
  </p>
  <h3><a name="HTTP.abort" href="#">HTTP.abort (key)</a></h3>
  <p>
    ...
  </p>
  <h3><a name="HTTP.observe" href="#"
  >HTTP.observe (state, req)</a></h3>
  <p>
    Applications that need to monitor responses progress can replace this
    method by their own event dispatcher. The one provided dispatches
    state changes to a map of HTTP request observers.
  </p>
  <pre
    class="synopsis"
    ><strong
    >HTTP.observe.rs[</strong>'GET hello-world.js'<strong
    >]</strong> = function (state) {
    switch (state) {
    case(2): // request sent
        ...
    case(3): // response status and headers complete
        ...
    case(4): // response body complete
        ...
    }
};</pre>
  <p>
    Note that only states 2, 3 and 4 are observed. Also, not all browsers 
    can report when a request was sent (that is state 2). But common 
    versions of IE, FireFox and Safari do.
  </p>
  <p>
    Apparently there are <a 
    href="http://www.quirksmode.org/blog/archives/2005/09/xmlhttp_notes_r_2.html"
    >wide differences</a>  between all implementations of XMLHttpRequest state 
    change. So it may be safer to consider that &quot;no browser correctly 
    supports <code>readyState</code> in all cases&quot; and restrict 
    applications to observe only the last two states.
  </p>
  <h3><a name="HTTP.except" href="#"
  >HTTP.except (key, message)</a></h3>
  <p>
    ...
  </p>
</div>
<script src="protocols.js" type="text/javascript"></script>
<script src="tests.js" type="text/javascript"></script>
</body>
</html>